<head>
<title>Manual Page</title>
</head>
<body>
<pre>
</pre><h2>NAME</h2><pre>
     cpl_complete_word,   cfc_file_start,    cfc_literal_escapes,
     cfc_set_check_fn,  cpl_add_completion, cpl_file_completions,
     cpl_last_error,   cpl_list_completions,    cpl_record_error,
     del_CplFileConf,     del_WordCompletion,    new_CplFileConf,
     new_WordCompletion - lookup possible completions for a word

</pre><h2>SYNOPSIS</h2><pre>
     #include &lt;stdio.h&gt;
     #include &lt;libtecla.h&gt;

     WordCompletion *new_WordCompletion(void);

     WordCompletion *del_WordCompletion(WordCompletion *cpl);

     #define CPL_MATCH_FN(fn) int (fn)(WordCompletion *cpl, \
                                       void *data, \
                                       const char *line, \
                                       int word_end)
     typedef CPL_MATCH_FN(CplMatchFn);

     CPL_MATCH_FN(cpl_file_completions);

     CplMatches *cpl_complete_word(WordCompletion *cpl,
                                   const char *line,
                                   int word_end, void *data,
                                   CplMatchFn *match_fn);

     int cpl_list_completions(CplMatches *result, FILE *fp,
                              int term_width);

     int cpl_add_completion(WordCompletion *cpl,
                            const char *line, int word_start,
                            int word_end, const char *suffix,
                            const char *type_suffix,
                            const char *cont_suffix);

     void cpl_record_error(WordCompletion *cpl,
                           const char *errmsg);

     const char *cpl_last_error(WordCompletion *cpl);



</pre><h2>DESCRIPTION</h2><pre>
     The  cpl_complete_word()  function  is  part  of  the  tecla
     library (see the <a href="libtecla.html">libtecla(3)</a> man page). It is usually called
     behind the scenes by <a href="gl_get_line.html">gl_get_line(3)</a>, but can also be  called
     separately.

     Given an input line containing an incomplete word to be com-
     pleted,  it  calls a user-provided callback function (or the
     provided file-completion callback function) to look  up  all
     possible  completion  suffixes  for  that word. The callback
     function is expected to look backward in the line,  starting
     from the specified cursor position, to find the start of the
     word to be completed, then to look up all  possible  comple-
     tions of that word and record them, one at a time by calling
     cpl_add_completion().


     Descriptions of the functions of this module are as follows:

       CompleteWord *new_CompleteWord(void)

     This  function   creates   the   resources   used   by   the
     cpl_complete_word()  function.  In  particular, it maintains
     the memory that is used to return  the  results  of  calling
     cpl_complete_word().

       CompleteWord *del_CompleteWord(CompleteWord *cpl)

     This function deletes the resources that were returned by  a
     previous  call to new_CompleteWord(). It always returns NULL
     (ie. a deleted object). It does nothing if the cpl  argument
     is NULL.

     The callback functions  which  lookup  possible  completions
     should be defined with the following macro (which is defined
     in libtecla.h).

       #define CPL_MATCH_FN(fn) int (fn)(WordCompletion *cpl, \
                                         void *data, \
                                         const char *line, \
                                         int word_end)

     Functions of this type are  called  by  cpl_complete_word(),
     and all of the arguments of the callback are those that were
     passed to said function. In particular,  the  line  argument
     contains the input line containing the word to be completed,
     and word_end is the index of the character that follows  the
     last  character  of  the incomplete word within this string.
     The callback is expected to look backwards from word_end for
     the start of the incomplete word. What constitutes the start
     of a word clearly depends on the application,  so  it  makes
     sense  for  the callback to take on this responsibility. For
     example, the  builtin  filename  completion  function  looks
     backwards  until it hits an unescaped space, or the start of
     the line.  Having found the start of the word, the  callback
     should  then  lookup  all possible completions of this word,
     and  record  each   completion   via   separate   calls   to
     cpl_add_completion().  If  the  callback  needs access to an
     application-specific symbol table, it can pass  it  and  any
     other  data  that  it  needs,  via  the  data argument. This
     removes any need for globals.

     The callback function should return 0 if no errors occur. On
     failure it should return 1, and register a terse description
     of the error by calling cpl_record_error().

       void cpl_record_error(WordCompletion *cpl,
                             const char *errmsg);

     The    last    error    message    recorded    by    calling
     cpl_record_error(),  can  subsequently be queried by calling
     cpl_last_error(), as described later.

       int cpl_add_completion(WordCompletion *cpl,
                              const char *line, int word_start,
                              int word_end, const char *suffix,
                              const char *type_suffix,
                              const char *cont_suffix);

     The cpl_add_completion() function is  called  zero  or  more
     times  by  the  completion  callback function to record each
     possible completion in the specified WordCompletion  object.
     These    completions    are    subsequently    returned   by
     cpl_complete_word(), as described later. The cpl, line,  and
     word_end  arguments  should be those that were passed to the
     callback function. The word_start  argument  should  be  the
     index  within the input line string of the start of the word
     that is being completed. This should  equal  word_end  if  a
     zero-length  string  is being completed. The suffix argument
     is the string that would have to be appended to  the  incom-
     plete  word  to complete it.  If this needs any quoting (eg.
     the addition of backslashes before special charaters) to  be
     valid  within  the  displayed  input  line,  this  should be
     included. A copy of the suffix string  is  allocated  inter-
     nally,  so  there  is  no  need to maintain your copy of the
     string after cpl_add_completion() returns.

     Note that in the array of  possible  completions  which  the
     cpl_complete_word() function returns, the suffix recorded by
     cpl_add_completion() is listed along with the concatentation
     of  this  suffix  with the word that lies between word_start
     and word_end in the input line.

     The type_suffix argument specifies an optional string to  be
     appended  to  the completion if it is displayed as part of a
     list of completions by cpl_list_completions(). The intention
     is  that  this indicate to the user the type of each comple-
     tion. For example, the file  completion  function  places  a
     directory  separator after completions that are directories,
     to indicate their nature to the user. Similary, if the  com-
     pletion were a function, you could indicate this to the user
     by setting type_suffix to "()". Note  that  the  type_suffix
     string  isn't  copied,  so  if  the argument isn't a literal
     string between speech marks, be sure that the string remains
     valid   for   at   least   as   long   as   the  results  of
     cpl_complete_word() are needed.

     The cont_suffix is a continuation suffix to  append  to  the
     completed word in the input line if this is the only comple-
     tion. This is something that isn't part  of  the  completion
     itself, but that gives the user an indication about how they
     might continue to extend the token.  For example, the  file-
     completion  callback  function adds a directory separator if
     the completed word is a directory.  If  the  completed  word
     were  a  function  name, you could similarly aid the user by
     arranging for an open parenthesis to be appended.

       CplMatches *cpl_complete_word(WordCompletion *cpl,
                                     const char *line,
                                     int word_end, void *data,
                                     CplMatchFn *match_fn);

     The cpl_complete_word() is normally called behind the scenes
     by  <a href="gl_get_line.html">gl_get_line(3)</a>, but can also be called separately if you
     separately allocate a  WordCompletion  object.  It  performs
     word  completion, as described at the beginning of this sec-
     tion. Its first argument is  a  resource  object  previously
     returned  by  new_CompleteWord().   The line argument is the
     input line string, containing the word to be completed.  The
     word_end argument contains the index of the character in the
     input line, that just follows the last character of the word
     to  be  completed. When called by gl_get_line(), this is the
     character over which the  user  pressed  TAB.  The  match_fn
     argument  is  the  function pointer of the callback function
     which will lookup  possible  completions  of  the  word,  as
     described  above,  and  the data argument provides a way for
     the application to pass arbitrary data to the callback func-
     tion.

     If no errors occur, the cpl_complete_word() function returns
     a  pointer to a CplMatches container, as defined below. This
     container is allocated as part of the cpl  object  that  was
     passed  to cpl_complete_word(), and will thus change on each
     call which uses the same cpl argument.

       typedef struct {
         char *completion;        /* A matching completion */
                                  /*  string */
         char *suffix;            /* The part of the */
                                  /*  completion string which */
                                  /*  would have to be */
                                  /*  appended to complete the */
                                  /*  original word. */
         const char *type_suffix; /* A suffix to be added when */
                                  /*  listing completions, to */
                                  /*  indicate the type of the */
                                  /*  completion. */
       } CplMatch;

       typedef struct {
         char *suffix;            /* The common initial part */
                                  /*  of all of the completion */
                                  /*  suffixes. */
         const char *cont_suffix; /* Optional continuation */
                                  /*  string to be appended to */
                                  /*  the sole completion when */
                                  /*  nmatch==1. */
         CplMatch *matches;       /* The array of possible */
                                  /*  completion strings, */
                                  /*  sorted into lexical */
                                  /*  order. */
         int nmatch;              /* The number of elements in */
                                  /*  the above matches[] */
                                  /*  array. */
       } CplMatches;

     If an error occurs  during  completion,  cpl_complete_word()
     returns  NULL. A description of the error can be acquired by
     calling the cpl_last_error() function.

       const char *cpl_last_error(WordCompletion *cpl);

     The cpl_last_error() function returns a terse description of
     the   error   which   occurred   on   the   last   call   to
     cpl_complete_word() or cpl_add_completion().

       int cpl_list_completions(CplMatches *result, FILE *fp,
                                int terminal_width);

     When the cpl_complete_word() function returns multiple  pos-
     sible  completions,  the cpl_list_completions() function can
     be called upon to list them, suitably  arranged  across  the
     available  width  of  the  terminal.  It  arranges  for  the
     displayed columns of completions to all have the same width,
     set   by   the  longest  completion.  It  also  appends  the
     type_suffix strings that were recorded with each completion,
     thus indicating their types to the user.


</pre><h2>THE BUILT-IN FILENAME-COMPLETION CALLBACK</h2><pre>
     By default the <a href="gl_get_line.html">gl_get_line(3)</a> function, passes the following
     completion  callback  function  to cpl_complete_word(). This
     function can also be used separately, either by  sending  it
     to  cpl_complete_word(), or by calling it directly from your
     own completion callback function.

       CPL_MATCH_FN(cpl_file_completions);

     Certain aspects of the behavior  of  this  callback  can  be
     changed  via  its  data  argument. If you are happy with its
     default behavior you can pass NULL in this argument.  Other-
     wise  it should be a pointer to a CplFileConf object, previ-
     ously allocated by calling new_CplFileConf().

       CplFileConf *new_CplFileConf(void);

     CplFileConf objects encapsulate the configuration parameters
     of cpl_file_completions(). These parameters, which start out
     with default values, can be changed by calling the  accessor
     functions described below.

     By default,  the  cpl_file_completions()  callback  function
     searches  backwards for the start of the filename being com-
     pleted, looking for the first un-escaped space or the  start
     of  the input line. If you wish to specify a different loca-
     tion, call cfc_file_start() with  the  index  at  which  the
     filename  starts  in  the input line. Passing start_index=-1
     re-enables the default behavior.

       void cfc_file_start(CplFileConf *cfc, int start_index);

     By default, when cpl_file_completions() looks at a  filename
     in  the input line, each lone backslash in the input line is
     interpreted as being a special character which  removes  any
     special significance of the character which follows it, such
     as a space which should be taken as  part  of  the  filename
     rather  than  delimiting  the  start  of the filename. These
     backslashes are thus ignored while looking for  completions,
     and  subsequently  added  before  spaces,  tabs  and literal
     backslashes in the list of completions.  To  have  unescaped
     backslashes    treated    as    normal    characters,   call
     cfc_literal_escapes() with a non-zero value in  its  literal
     argument.

       void cfc_literal_escapes(CplFileConf *cfc, int literal);

     By default, cpl_file_completions() reports all  files  who's
     names  start with the prefix that is being completed. If you
     only want a selected subset of these files to be reported in
     the list of completions, you can arrange this by providing a
     callback function which takes the full pathname of  a  file,
     and  returns  0  if  the file should be ignored, or 1 if the
     file should be included  in  the  list  of  completions.  To
     register  such a function for use by cpl_file_completions(),
     call cfc_set_check_fn(), and pass it a pointer to the  func-
     tion,  together  with  a  pointer to any data that you would
     like passed to this callback whenever  it  is  called.  Your
     callback can make its decisions based on any property of the
     file, such as the filename itself, whether the file is read-
     able, writable or executable, or even based on what the file
     contains.

       #define CPL_CHECK_FN(fn) int (fn)(void *data, \
                                         const char *pathname)
       typedef CPL_CHECK_FN(CplCheckFn);

       void cfc_set_check_fn(CplFileConf *cfc,
                             CplCheckFn *chk_fn, void *chk_data);

     The cpl_check_exe() function is a provided callback  of  the
     above  type, for use with cpl_file_completions(). It returns
     non-zero if the filename that it is given represents a  nor-
     mal  file that the user has execute permission to. You could
     use this to have cpl_file_completions()  only  list  comple-
     tions of executable files.

     When you have finished with a CplFileConf variable, you  can
     pass  it  to  the  del_CplFileConf()  destructor function to
     reclaim its memory.

       CplFileConf *del_CplFileConf(CplFileConf *cfc);



</pre><h2>THREAD SAFETY</h2><pre>
     In multi-threaded programs, you should use the  libtecla_r.a
     version  of the library. This uses POSIX reentrant functions
     where available (hence the _r suffix), and disables features
     that  rely on non-reentrant system functions. In the case of
     this module, the only disabled feature is  username  comple-
     tion in ~username/ expressions, in cpl_file_completions().

     Using the libtecla_r.a version of the library, it is safe to
     use  the facilities of this module in multiple threads, pro-
     vided that each thread uses a separately allocated  WordCom-
     pletion  object.  In  other words, if two threads want to do
     word completion, they should each call  new_WordCompletion()
     to allocate their own completion objects.


</pre><h2>FILES</h2><pre>
     libtecla.a    -    The tecla library
     libtecla.h    -    The tecla header file.


</pre><h2>SEE ALSO</h2><pre>
     <a href="libtecla.html">libtecla(3)</a>,       <a href="gl_get_line.html">gl_get_line(3)</a>,        <a href="ef_expand_file.html">ef_expand_file(3)</a>,
     <a href="pca_lookup_file.html">pca_lookup_file(3)</a>


</pre><h2>AUTHOR</h2><pre>
     Martin Shepherd  (mcs@astro.caltech.edu)


















































</pre>
</body>
